<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>array manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> array</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="array.htm#M2" NAME="L26">NAME</A>
<DL><DD>array &mdash; Manipulate array variables</DD></DL>
<DD><A HREF="array.htm#M3" NAME="L27">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="array.htm#M4" NAME="L28">DESCRIPTION</A>
<DL class="description">
<DD><A HREF="array.htm#M5" NAME="L29"><B>array anymore </B><I>arrayName searchId</I></A>
<DD><A HREF="array.htm#M6" NAME="L30"><B>array donesearch </B><I>arrayName searchId</I></A>
<DD><A HREF="array.htm#M7" NAME="L31"><B>array exists </B><I>arrayName</I></A>
<DD><A HREF="array.htm#M8" NAME="L32"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A>
<DD><A HREF="array.htm#M9" NAME="L33"><B>array names </B><I>arrayName</I> ?<I>mode</I>? ?<I>pattern</I>?</A>
<DD><A HREF="array.htm#M10" NAME="L34"><B>array nextelement </B><I>arrayName searchId</I></A>
<DD><A HREF="array.htm#M11" NAME="L35"><B>array set </B><I>arrayName list</I></A>
<DD><A HREF="array.htm#M12" NAME="L36"><B>array size </B><I>arrayName</I></A>
<DD><A HREF="array.htm#M13" NAME="L37"><B>array startsearch </B><I>arrayName</I></A>
<DD><A HREF="array.htm#M14" NAME="L38"><B>array statistics </B><I>arrayName</I></A>
<DD><A HREF="array.htm#M15" NAME="L39"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A>
</DL>
<DD><A HREF="array.htm#M16" NAME="L40">EXAMPLES</A>
<DD><A HREF="array.htm#M17" NAME="L41">SEE ALSO</A>
<DD><A HREF="array.htm#M18" NAME="L42">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
array &mdash; Manipulate array variables
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command performs one of several operations on the
variable given by <I>arrayName</I>.
Unless otherwise specified for individual commands below,
<I>arrayName</I> must be the name of an existing array variable.
The <I>option</I> argument determines what action is carried
out by the command.
The legal <I>options</I> (which may be abbreviated) are:
<P>
<DL class="description">
<DT><A NAME="M5"><B>array anymore </B><I>arrayName searchId</I></A><DD>
Returns 1 if there are any more elements left to be processed
in an array search, 0 if all elements have already been
returned.
<I>SearchId</I> indicates which search on <I>arrayName</I> to
check, and must have been the return value from a previous
invocation of <B>array startsearch</B>.
This option is particularly useful if an array has an element
with an empty name, since the return value from
<B>array nextelement</B> will not indicate whether the search
has been completed.
<P><DT><A NAME="M6"><B>array donesearch </B><I>arrayName searchId</I></A><DD>
This command terminates an array search and destroys all the
state associated with that search.  <I>SearchId</I> indicates
which search on <I>arrayName</I> to destroy, and must have
been the return value from a previous invocation of
<B>array startsearch</B>.  Returns an empty string.
<P><DT><A NAME="M7"><B>array exists </B><I>arrayName</I></A><DD>
Returns 1 if <I>arrayName</I> is an array variable, 0 if there
is no variable by that name or if it is a scalar variable.
<P><DT><A NAME="M8"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
Returns a list containing pairs of elements.  The first
element in each pair is the name of an element in <I>arrayName</I>
and the second element of each pair is the value of the
array element.  The order of the pairs is undefined.
If <I>pattern</I> is not specified, then all of the elements of the
array are included in the result.
If <I>pattern</I> is specified, then only those elements whose names
match <I>pattern</I> (using the matching rules of
<B><A HREF="../TclCmd/string.htm">string match</A></B>) are included.
If <I>arrayName</I> is not the name of an array variable, or if
the array contains no elements, then an empty list is returned.
If traces on the array modify the list of elements, the elements
returned are those that exist both before and after the call to
<B>array get</B>.
<P><DT><A NAME="M9"><B>array names </B><I>arrayName</I> ?<I>mode</I>? ?<I>pattern</I>?</A><DD>
Returns a list containing the names of all of the elements in
the array that match <I>pattern</I>.  <I>Mode</I> may be one of
<B>-exact</B>, <B>-glob</B>, or <B>-regexp</B>.  If specified, <I>mode</I>
designates which matching rules to use to match <I>pattern</I> against
the names of the elements in the array.  If not specified, <I>mode</I>
defaults to <B>-glob</B>.  See the documentation for <B><A HREF="../TclCmd/string.htm">string match</A></B>
for information on glob style matching, and the documentation for
<B><A HREF="../TclCmd/regexp.htm">regexp</A></B> for information on regexp matching.
If <I>pattern</I> is omitted then the command returns all of
the element names in the array.  If there are no (matching) elements
in the array, or if <I>arrayName</I> is not the name of an array
variable, then an empty string is returned.
<P><DT><A NAME="M10"><B>array nextelement </B><I>arrayName searchId</I></A><DD>
Returns the name of the next element in <I>arrayName</I>, or
an empty string if all elements of <I>arrayName</I> have
already been returned in this search.  The <I>searchId</I>
argument identifies the search, and must have
been the return value of an <B>array startsearch</B> command.
Warning:  if elements are added to or deleted from the array,
then all searches are automatically terminated just as if
<B>array donesearch</B> had been invoked; this will cause
<B>array nextelement</B> operations to fail for those searches.
<P><DT><A NAME="M11"><B>array set </B><I>arrayName list</I></A><DD>
Sets the values of one or more elements in <I>arrayName</I>.
<I>list</I> must have a form like that returned by <B>array get</B>,
consisting of an even number of elements.
Each odd-numbered element in <I>list</I> is treated as an element
name within <I>arrayName</I>, and the following element in <I>list</I>
is used as a new value for that array element.
If the variable <I>arrayName</I> does not already exist
and <I>list</I> is empty,
<I>arrayName</I> is created with an empty array value.
<P><DT><A NAME="M12"><B>array size </B><I>arrayName</I></A><DD>
Returns a decimal string giving the number of elements in the
array.
If <I>arrayName</I> is not the name of an array then 0 is returned.
<P><DT><A NAME="M13"><B>array startsearch </B><I>arrayName</I></A><DD>
This command initializes an element-by-element search through the
array given by <I>arrayName</I>, such that invocations of the
<B>array nextelement</B> command will return the names of the
individual elements in the array.
When the search has been completed, the <B>array donesearch</B>
command should be invoked.
The return value is a
search identifier that must be used in <B>array nextelement</B>
and <B>array donesearch</B> commands; it allows multiple
searches to be underway simultaneously for the same array.
It is currently more efficient and easier to use either the <B>array
get</B> or <B>array names</B>, together with <B><A HREF="../TclCmd/foreach.htm">foreach</A></B>, to iterate
over all but very large arrays.  See the examples below for how to do
this.
<P><DT><A NAME="M14"><B>array statistics </B><I>arrayName</I></A><DD>
Returns statistics about the distribution of data within the hashtable
that represents the array.  This information includes the number of
entries in the table, the number of buckets, and the utilization of
the buckets.
<P><DT><A NAME="M15"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
Unsets all of the elements in the array that match <I>pattern</I> (using the
matching rules of <B><A HREF="../TclCmd/string.htm">string match</A></B>).  If <I>arrayName</I> is not the name
of an array variable or there are no matching elements in the array, no
error will be raised.  If <I>pattern</I> is omitted and <I>arrayName</I> is
an array variable, then the command unsets the entire array.
The command always returns an empty string.
<P></DL>
<H3><A NAME="M16">EXAMPLES</A></H3>
<PRE><B>array set</B> colorcount {
    red   1
    green 5
    blue  4
    white 9
}

foreach {color count} [<B>array get</B> colorcount] {
    puts &quot;Color: $color Count: $count&quot;
}
  <B><font size="+1">&rarr;</font></B> Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1

foreach color [<B>array names</B> colorcount] {
    puts &quot;Color: $color Count: $colorcount($color)&quot;
}
  <B><font size="+1">&rarr;</font></B> Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1

foreach color [lsort [<B>array names</B> colorcount]] {
    puts &quot;Color: $color Count: $colorcount($color)&quot;
}
  <B><font size="+1">&rarr;</font></B> Color: blue Count: 4
    Color: green Count: 5
    Color: red Count: 1
    Color: white Count: 9

<B>array statistics</B> colorcount
  <B><font size="+1">&rarr;</font></B> 4 entries in table, 4 buckets
    number of buckets with 0 entries: 1
    number of buckets with 1 entries: 2
    number of buckets with 2 entries: 1
    number of buckets with 3 entries: 0
    number of buckets with 4 entries: 0
    number of buckets with 5 entries: 0
    number of buckets with 6 entries: 0
    number of buckets with 7 entries: 0
    number of buckets with 8 entries: 0
    number of buckets with 9 entries: 0
    number of buckets with 10 or more entries: 0
    average search distance for entry: 1.2</PRE>
<H3><A NAME="M17">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/list.htm">list</A></B>, <B><A HREF="../TclCmd/string.htm">string</A></B>, <B><A HREF="../TclCmd/variable.htm">variable</A></B>, <B><A HREF="../TclCmd/trace.htm">trace</A></B>, <B><A HREF="../TclCmd/foreach.htm">foreach</A></B>
<H3><A NAME="M18">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#array">array</A>, <A href="../Keywords/E.htm#element names">element names</A>, <A href="../Keywords/S.htm#search">search</A>
<div class="copy">Copyright &copy; 1993-1994 The Regents of the University of California.
<BR>Copyright &copy; 1994-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
